Agave - The Adventure island 3 editor
Version 1.21 by master higgins (A.K.A. aioria1981 and megaman_exe)
=====================================

 My homepage
 http://h1.ripway.com/aioria1981
______________________________________________________________________

 CONTENTS
______________________________________________________________________

 1. Instructions
   1.1 Requirements
   1.2 Overview
   1.3 Usage
 2. Legal Notice
 3. Contact Information
 4. Changes

______________________________________________________________________

 1. Instructions
______________________________________________________________________

 This program is intended to edit some data of the Adventure Island 3
 NES rom, which can be any of the american or japanese version (called
 Takahashi Meijin no Daibouken Jima 3). The data that is edited by the
 editor comprises the one related with enemies, items and platforms
 (which I'll refer as objects) and screens (which I may refer also as
 scenes). In detail, the editor is capable of:

 - Object appearance manipulation (changing one enemy to another 
 type of enemy)
 - Object positioning (change the position of the objects in the level)
 - Scene changing (Change one scene to another scene, chosen among a
 given group)

 1.1 Requirements
 ----------------
 
 - At least jre 1.1 installed 
 - A moderate fast PC. (Over 500 Mhz should be ok)
 - Should run on any platform, as it's done in java
 - Windows users should double click "agave.jar". If you cannnot execute
 the program (Winrar opening, file type no recognized), just execute 
 command.bat (ignore the black screen). If jre isn't installed, go
 to http://java.sun.com/javase/downloads/index.jsp to download it.
 - Linux users should execute it just by typing "java -jar Agave.jar"
 or an easier method.

 1.2 Overview
 ------------
 
 Adventure island 3 level format is a bit tricky. The levels are
 structured in this way

 Level
   |-Scenes
   |   |- Structures
   |         |- TSA blocks
   |                |- pixel data
   |-Enemies

 The level contains scenes and enemies, but the scenes are also
 composed of structures, that are 4x4 tsa blocks joined in a square.
 The tsa blocks are simply 8x8 pixel blocks, in 2bpp, 3 colors and
 a transparent color. Scenes, structures and tsa blocks are numbered
 from 0 to a given value (for example, the valid indexes of the
 ice cave goes from 0x00 to 0x0d in hexadecimal.

 The editor just edits the scenes, that is, it doesn't go deep to the
 detail of the structures or tsa blocks. In this way, you can only
 change one scene to another (by changing the index to another index)

 About the enemies, the editor also does the same, changing one enemy
 index (which I'll also call its ID) to another index, to look different
 and BEHAVE different (the behaviour of the chosen enemy). Also, the 
 enemies coordinates can be changed.

 Theres a concept involved in the enemies edition, which is called a
 "bank". A bank is simply a set of pointers that tells the rom what
 graphics to load to show objects correctly. In this way, I tried
 my best to give the freedom to change this bank, but with some
 restrictions (which are more meant to be a guide), so no invalid
 values can be put in the pointer. Aditionally, the bank can change
 during the run though the level.

 Said this, let's go to the usage:

 1.3 Usage
 ------------
 
 To use the editor, you must first load a valid Adventure island 3 rom.
 Starting the editor will only show the load button, so upon choosing
 the rom, all the other options will appear. By the way, the rom 
 detection is very rough, but it does the job.
  
 The editor offers to modes of edition:

 - Scene mode
 - Object mode

 In scene mode you are shown a screen which is 2x2 scenes large. 
 There's a hollow square flashing to show what scene is currently
 selected. (I also call this square a cell)
 
 The scrolling controls are as follows:

 Left arrow key: Move one scene left. 
 Right arrow key: Move one scene right. 
 Up arrow key: Move one scene up. 
 Down arrow key: Move one scene down. 

 Ctrl+Left arrow key: Move 4 scenes left. 
 Ctrl+Right arrow key: Move 4 scenes right. 
 Ctrl+Up arrow key: Move 4 scenes up. 
 Ctrl+Down arrow key: Move 4 scenes down. 

 Home: Move to the first scene in the current row. 
 End: Move to the last scene in the current row. 
 Page up: Move to the first scene in the current column. 
 Page up: Move to the last scene in the current column. 

 The editing controls are as follows 

 Spacebar: Change the cell to the next scene in order. 
 Backspace: Change the cell to the previous scene in order. 

 Ctrl+Spacebar: Change the cell to the scene 4 places forward of the current scene in order. 
 Ctrl+Backspace: Change the cell to the scene 4 places back of the current scene in order. 
 Shift+Spacebar: Change the cell to the last scene of the tileset. 
 Shift+Backspace: Change the cell to the first scene of the tileset. 

 Left click: The same as spacebar. 
 Right click: The same as backspace. 
 Ctrl+Left click: The same as Ctrl+spacebar. 
 Ctrl+Right click: The same as Ctrl+backspace. 
 Shift+Left click: The same as Shift+spacebar. 
 Shift+Right click: The same as Shift+backspace.


 In object mode, I tried to make it easier to move objects, so
 to MOVE them you just have to DRAG them. To help the object
 selection, the cursor changes to a hand when over an object.

 To change the object to another object, you have to CHOOSE IT by
 pushing the Choose Object button IN THE UPPER RIGHT CORNER. An 
 interactive dialog will appear. You can choose any enemy from 
 the enemy pages. To change a page, push the "<" or ">" buttons. 
 Also, you can enable the old method which consist in a list in 
 the upper right corner. To change between the old and new method, 
 click the "interactive" checkbox in the upper right corner. After
 choosing an enemy selection method, choose an enemy, hover over
 an object on the screen and and then RIGHT CLICK on it.  
 I tried my best to put names to the objects, but there are some 
 that are unused or others that are used but have an unknown 
 purpose (and are invisible). This is the following control list
 for objects:

 mouse drag over an object: Move the object
 right click on an object: change the object to the one
                           chosen in the object list
 hover an object and push delete key: delete that object (Actually
                                      the object is moved very far
                                      away, further than the lower
                                      right corner)
 ctrl+delete: delete all objects (in the same fashion explained
                                  above)

 Objects that won't show well in the level are shown by either a
 "?", a "(/)" or a "!". A "?" means that the object is going to be shown
 garbled, and it's because the bank chosen for the level doesn't
 fit the bank the object is made for, or the object is located in
 an area where the bank changes, so you can either move the object
 until it shows well, or change the bank (Explained later). A "!"
 means the object will be invisible. This happens when you put an
 object too low in the stage. Last, the "(/)" symbol is shown in stages 
 that  have a constraint that doesn't allow two or more objects to be
 in the same (or almost the same) vertical position.

 There is a drop-down list to choose the stage, and another drop-down
 list to choose the bank from a predefined group. The latter list
 will only appear if the manual bank selection is disabled (the 
 "Manual bank" checkbox). The manual bank selection can be reached 
 by enabling the checkbox and pushing the "Choose bank" button.

 The Custom bank selection dialog provides a list of predefined
 banks also, but this will only apply to the first scenes of the
 level, the other scenes will change according to the diagram shown
 on that window. The bank change sequence can be altered by
 choosing the bank change sequence drop-down list. The diagram
 shows areas with colors, that represent the bank used in that area.
 The descriptions of the colors are displayed below the diagram. The
 numbers and letters in the diagram represent the screen number
 horizontally, in hexadecimal.

 Example
 Imagine that:
 ==== : is red
 ---- : is dark purple
 ____ : is magenta

 so
 0 1 2 3 4 5 6 7 8 9 a b c d e f
 ============------______________

 will mean that from the first screen to the screen number 5, the bank
 used will be coastal clash...A (in which enemies like crows, and snails
 look ok.), then from screen 6 to screen 8 the bank used for the level
 is coastal clash...F (in which enemies like pigs, and crabs look ok.),
 and then from screen 9 to screen 15 (0x0f) the bank used for the level
 is coastal clash...D (in which moles and clouds look ok).

 There are many enemies that look ok in many banks, some on all of them.

 If you move an enemy beyond the bank area (for example, moving a snail
 further away than screen 5, it will look garbled. But sometimes it may
 work, because some enemies are in movement, and for example, a crow in
 the left edge of scene 6 may look well, because crows move left and will
 enter in the "good-looking area"

 Higgins (our hero) vertical position can be change with the scrollbars
 in the main window. One scrollbar is for small movements (16 pixels) and 
 the other is for large changes (on scene tall). A combination of these
 will place higgins in his starting position.

 And last, scenes 1-5 and 8-B SHARE SCENES!!!!. So if you change an scene
 in 1-5, it will appear exactly as in 8-B and viceversa. Fortunately,
 enemy data is not shared. (Or else it would be a deja vu).

 I hope you enjoy this editor. For comments and doubts, visit my page. 
 There should be the contact information.

 Cya!
______________________________________________________________________

 2. Legal Notice
______________________________________________________________________

 Agave (which we will also refer as the software) is not supported 
 by any commercial entity.

 The Software can be freely distributed for non-profit use only. 
 No goods, services, or money can be charged for the Software in any
 form, nor may it be bundled as part of another package that is
 commercial in nature.

 The Software is provided AS IS, and its use is at your own risk.
 Anyone mentioned in this document will not be held liable for any
 damages, direct or otherwise, arising from its use or presence.

______________________________________________________________________

 3. Contact Information
______________________________________________________________________


 master higgins
   www:   http://h1.ripway.com/aioria1981
   e-mail:sigmavirus@gmail.com
   msn:   megaman_exe@hotmail.com   
______________________________________________________________________

 4. Changes

 v1.0 : First version. Enemy selection works with a list.
 v1.1 : Second version. Enemy selection now can be done with an interactive 
	dialog showing the enemies graphics. Fixed many bugs related to the
	values and strings used.
 v1.2 : Third version. Fixed bugs about moving objects out of the limits of the
	drawing area. Added warnings about objects that may become invisible at
	certain positions. Interactive enemy selection enabled by default (It's
	easier to choose).
 v1.21 : Fixed a bug which corrupts world 1 map tile arrange when changing the
	 first scene in level 4-3. Unfortunately, the rom is coded in a way that
	 a pointer is stored in the very first offset for the first scene in the
         level (value = 0x00), so changing it messes all the world 1 map. As it
	 was way beyond my skills, I added code to the editor to prevent (and
	 also correct) the scene chosen for the first cell in 4-3. In other words, 
	 in level 4-3 the first scene cell will have the value 0x00 ALWAYS. You'll 
	 have to live with that constraint :(